Inside Macintosh: /

QuickDraw 3D RAVE / QuickDraw 3D RAVE Reference

QuickDraw 3D RAVE Routines / Public Draw Context Methods

TQARenderStart

A drawing engine must define a method to initialize a draw context before the engine performs any rendering into that context.

typedef void (*TQARenderStart) (
                                const TQADrawContext *drawContext, 
                                const TQARect *dirtyRect, 
                                const TQADrawContext *initialContext);

drawContext

A draw context.

dirtyRect

The minimum area of the specified draw context to clear, or the value NULL.

initialContext

A previously cached draw context, or the value NULL.

DESCRIPTION

Your TQARenderStart function should perform any operations necessary to initialize the draw context specified by the drawContext parameter. This includes clearing the z buffer and the color buffers of the draw context. If the value of the initialContext parameter is NULL, then your TQARenderStart function should clear the z buffer to 1.0 and set the color buffers to the values of the kQATag_ColorBG_a, kQATag_ColorBG_r, kQATag_ColorBG_g, and kQATag_ColorBG_b draw context state variables. If, however, the value of the initialContext parameter is not NULL, then your TQARenderStart function should use the previously cached draw context specified by that parameter to initialize the draw context specified by the drawContext parameter.

The dirtyRect parameter indicates the minimum area of the specified draw context that should be cleared on initialization. If the value of the dirtyRect parameter is NULL, the entire draw context is cleared. If the value of the dirtyRect parameter is not NULL, it indicates the rectangle in the draw context to clear. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed. However, the interpretation of the dirtyRect parameter is dependent on the drawing engine, which may choose to initialize the entire draw context. As a result, code calling your QARenderStart function should not use this parameter as a means to avoid clearing all of a draw context or to perform incremental rendering. Instead, that code should use the initialContext parameter to achieve such effects.

SPECIAL CONSIDERATIONS

Applications should call QARenderStart before performing any rendering operations in the specified draw context, and they should call either QARenderEnd to signal the end of rendering operations or QARenderAbort to cancel rendering operations. However, when a drawing engine is performing OpenGL rendering, the QARenderStart function operates just like the OpenGL function glClear. In OpenGL mode, it is not necessary that a call to QARenderStart always be balanced by a matching call to QARenderEnd, and drawing commands may occur at any time.